Quick Index

Overview


javadoc is a tool in the java toolbox (it is a sister of "javac" and "java").

The purpose of javadoc is to generate user-friendly (HTML/browser) documents of our JAVA files.

How To


Sophisticated IDE's like Eclipse, etc have their own techniques for javadoc.

But here we'll describe the basic approach to generating javadocs.

When coding for JavaDoc:


  • Start comment with /**
  • End comment with */
 

1
/** Set both firstName and lastName
2
*/ public void setNames(String aFirstName, String aLastName) { this.firstName = aFirstName; this.lastName = aFirstName; }
We may JavaDoc these element types:


  • Public class header
  • Public Instance Variable Declaration
  • Public Constructor (any or all)
  • Public Method (any or all)

NOTE WELL -- Generally instance variables are private, so we would not java doc those.
//Start Person
1
public class Person {
2
public String firstName; private String lastName;
3
public Person(String aFirstName, String aLastName) { this.firstName = aFirstName; this.lastName = aLastName; }
4
public void setNames(String aFirstName, String aLastName) { this.firstName = aFirstName; this.lastName = aFirstName; } public String getFullName() { String fullName; fullName = this.firstName + " " + lastName; return fullName; } public String toString() { return "Person: " + this.getFullName(); } }
Here we have documented the Person class.
/** Person class -- minimal model of person */
public class Person {

	private String firstName;
	private String lastName;

	/** Contruct Person with firstName and lastName */
	public Person(String aFirstName, String aLastName) {
		this.firstName = aFirstName;
		this.lastName = aLastName;
	}

	/** Set both firstName and lastName */
	public void setNames(String aFirstName, String aLastName) {
		this.firstName = aFirstName;
		this.lastName = aFirstName;
	}

	/** Get Full Name */
	public String getFullName() {
		String fullName;
		fullName = this.firstName + " " + lastName;
		return fullName;
	}

	/** Nice descriptive string of person */
	public String toString() {
		return "Person: " + this.getFullName();
	}

}

Here we have documented the Planet class.
/** Planet class -- Simple model of a planet */
public class Planet {

	private String name;
	private int radius;		//miles

	/** Contruct planet with name and radius (in miles) */
	public Planet(String aName, int aRadius) {
		this.name = aName;
		this.radius = aRadius;
	}

	/** Set planet name */
	public void setName(String aName) {
		this.name = aName;
	}

	/** Set planet radius */
	public void setRadius(int aRadius) {
		this.radius = aRadius;
	}

	/** Computed planet circumference (assuming sphere) */
	public int computeCircumference() {
		//Compute distance around the planet
		//Note: Hardcoding PI (3.1416) to simplify example
		double result;
		int rounded;
		//2 * PI * r
		result = 2 * 3.1416 * this.radius;
		//convert to int by calling another method
		rounded = round(result);
		return rounded;
	}

	private int round(double num) {
		//round num to integer
		//e.g. 5.1 -> 5
		//e.g. 5.7 -> 6
		return (int)Math.round(num);
	}

	/** Nice descriptive string of planet */
	public String toString() {
		String units = " miles";
		int r, c;
		String rString, cString, fullString;
		r = this.radius;
		c = this.computeCircumference();
		rString = " -- radius = " + r + units;
		cString = " -- circumference = " + c + units;
		fullString = "Planet" + rString + cString;
		return fullString;
	}

}

Generating JavaDoc From JAVA Files


Here we'll show an example of generating java docs from JAVA source files.

Let us say we have the following:

PathDescription
C:\Work\Courses\Play\Project1SourceLocation of source files
C:\Work\Courses\Play\Project1DocsTarget output location (of documentation)


This is the (Windows) script we could use to generate the java documentation:

SET SourcePath=C:\Work\Courses\Play\Project1Source
SET OutputPath=C:\Work\Courses\Play\Project1Docs
SET MyClassPath=.

cd "%SourcePath%"
javadoc -classpath "%MyClassPath%" *.java -d "%OutputPath%"

pause


Note that javadoc uses classpath just like the javac and java commands.

In the output directory we would have a file named "allclasses-index.html" that is our doc index.

Another Example: Explicit JAVA files

SET SourcePath=C:\Work\Courses\Play\Project1Source
SET OutputPath=C:\Work\Courses\Play\Project1Docs
SET MyClassPath=.

cd "%SourcePath%"
javadoc -cp "%MyClassPath%" -d "%OutputPath%" model\Rectangle.java test\RectangleTest.java

pause


Generating JavaDoc From Java Packages


Here we'll show an example of generating java docs from Java packages.

Let us say we have the following:

PathDescription
ds.linear.pubpackage path to source code we want to document
C:\Work\Courses\Play\srcOur classpath (i.e. "src" is the parent directory containing child direcotry "ds")
C:\Work\Courses\Play\LinearPubDocsTarget output location (of documentation)


This is the (Windows) script we could use to generate the java documentation:

SET MyClassPath=C:\Work\Courses\Play\src
SET OutputPath=C:\Work\Courses\Play\LinearPubDocs
SET Package=ds.linear.pub

javadoc -classpath "%MyClassPath%" -d "%OutputPath%" %Package%

pause


Note that javadoc uses classpath just like the javac and java commands.

In the output directory we would have a file named "allclasses-index.html" that is our doc index.

References














Navigation